{ "openapi": "3.1.0", "info": { "title": "ConveRact Agent Reliability API", "version": "2026-09-13", "description": "Session-only administrator API. See /agent-reliability-guide.md for coverage, provider setup and limits." }, "servers": [ { "url": "/api/v1" } ], "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "atlas_access" } } }, "paths": { "/reliability": { "get": { "tags": [ "Agent reliability" ], "summary": "List scoped trace summaries, simulation jobs, batch investigations, knowledge gaps and reusable blocks", "description": "List scoped trace summaries, simulation jobs, batch investigations, knowledge gaps and reusable blocks.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [], "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/traces/{id}": { "get": { "tags": [ "Agent reliability" ], "summary": "Read one trace with nested, redacted, bounded spans", "description": "Read one trace with nested, redacted, bounded spans.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/versions/{id}/preview": { "post": { "tags": [ "Agent reliability" ], "summary": "Preview deterministic seed/context/concern combinations without model calls", "description": "Preview deterministic seed/context/concern combinations without model calls. Body: count (1–5000), maxCalls (2–10000), acknowledgeUsage:true, contexts and concerns (1–50 strings each).", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/versions/{id}/simulations": { "post": { "tags": [ "Agent reliability" ], "summary": "Queue candidate/baseline comparisons", "description": "Queue candidate/baseline comparisons. Same body as preview; maxCalls must cover twice count. Workspace usage charges apply.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/simulations/{id}": { "get": { "tags": [ "Agent reliability" ], "summary": "Read job progress and retained examples; total counts all selected cases", "description": "Read job progress and retained examples; total counts all selected cases.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/simulations/{id}/cancel": { "post": { "tags": [ "Agent reliability" ], "summary": "Request cancellation after any currently executing comparison", "description": "Request cancellation after any currently executing comparison.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/agents/{id}/gate": { "patch": { "tags": [ "Agent reliability" ], "summary": "Require minimumCases (1–5000) and reviewed:true", "description": "Require minimumCases (1–5000) and reviewed:true. Minimum cannot decrease; fresh passing simulation is required for publication.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/gaps/scan": { "post": { "tags": [ "Agent reliability" ], "summary": "Scan days (1–90, default 30) of customer questions; report retrieval coverage and potential gaps", "description": "Scan days (1–90, default 30) of customer questions; report retrieval coverage and potential gaps.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/gaps/{id}": { "patch": { "tags": [ "Agent reliability" ], "summary": "Dismiss a potential gap with status:DISMISSED", "description": "Dismiss a potential gap with status:DISMISSED.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/gaps/{id}/draft": { "post": { "tags": [ "Agent reliability" ], "summary": "Create an unpublished FAQ from verified title (3–200 chars) and content (20–12000 chars)", "description": "Create an unpublished FAQ from verified title (3–200 chars) and content (20–12000 chars).", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/explorer": { "get": { "tags": [ "Agent reliability" ], "summary": "Compare recorded periods using optional days (1–90, default 7) and channel (default ALL) query parameters", "description": "Compare recorded periods using optional days (1–90, default 7) and channel (default ALL) query parameters.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [], "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/explorer/jobs": { "post": { "tags": [ "Agent reliability" ], "summary": "Queue cited batch investigation", "description": "Queue cited batch investigation. Body: question (10–1000 chars), days (1–90), maxConversations (1–5000), maxCalls (1–200), acknowledgeUsage:true. One model call per 25 conversations.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/explorer/jobs/{id}": { "get": { "tags": [ "Agent reliability" ], "summary": "Read all retained batch findings, citations and coverage for one investigation", "description": "Read all retained batch findings, citations and coverage for one investigation.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/explorer/jobs/{id}/cancel": { "post": { "tags": [ "Agent reliability" ], "summary": "Request cancellation after the currently executing investigation batch", "description": "Request cancellation after the currently executing investigation batch.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/voice": { "post": { "tags": [ "Agent reliability" ], "summary": "Compare original and impaired WAV recognition", "description": "Compare original and impaired WAV recognition. Body: audio (base64 mono 16-bit PCM WAV, up to 40 seconds), expected transcript, noise (0–0.3), dropoutMs (0–2000), seed and acknowledgeUsage:true. Two billable speech requests.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } }, "/reliability/journeys/compose": { "post": { "tags": [ "Agent reliability" ], "summary": "Create paused workflow from name and 1–12 blocks", "description": "Create paused workflow from name and 1–12 blocks. WORKFLOW blocks need id and expectedVersion; API_ACTION blocks need id and optional when (ALWAYS, NEGATIVE, HIGH_INTENT). Expanded total cannot exceed 12 steps.", "security": [ { "cookieAuth": [] } ], "x-roles": [ "TENANT_ADMIN" ], "parameters": [ { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": {} } } }, "responses": { "200": { "description": "Scoped result; inspect job status and coverage." }, "201": { "description": "Unpublished resource created." }, "202": { "description": "Background work queued." }, "400": { "description": "Invalid request." }, "401": { "description": "Session required." }, "403": { "description": "Administrator role or CSRF required." }, "404": { "description": "Record unavailable in this tenant." }, "409": { "description": "Busy, stale, locked or unsupported state." }, "429": { "description": "Usage or scheduling limit." }, "502": { "description": "Provider or evidence validation failed." } } } } } }