{ "openapi": "3.1.0", "info": { "title": "ALPNAI Agent API", "version": "0.1.1", "description": "Analyze supplied AI-agent measurements and save aggregate reports with an explicit Projects owner grant. Evidence calls default to sandbox. Live x402 requires current commercial availability, an owner-authorized mandate and an approved billing profile. Read /api/v1/catalog for current availability; live collection remains closed until commercial activation.", "contact": { "email": "frederic@alpnor.com" } }, "servers": [ { "url": "https://alpnai.com" } ], "paths": { "/api/v1/snapshot": { "get": { "operationId": "purchase_snapshot", "summary": "Evidence purchase with explicit mode and current eligibility checks", "security": [ { "AgentKey": [] } ], "parameters": [ { "in": "header", "name": "X-ALPNAI-Mode", "required": true, "schema": { "type": "string", "enum": [ "sandbox", "live" ] }, "description": "Use live explicitly for x402. Commercial activation, owner mandate and billing eligibility are required." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } }, { "name": "X-AlpNAI-Mandate", "in": "header", "required": false, "description": "Required in live mode: an active owner-authorized mandate for this agent.", "schema": { "type": "string", "pattern": "^[-a-zA-Z0-9]{8,80}$" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 signed exact payment payload. Only submit after checking the original 402 quote and owner wallet policy. Never send a private key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sandbox receipt, or a finalized live receipt with its result. Inspect settled and network." }, "400": { "description": "Invalid input" }, "401": { "description": "Unauthorized agent" }, "403": { "description": "Budget exhausted" }, "409": { "description": "Idempotency conflict" }, "503": { "description": "Commerce unavailable or billing qualification required; no payment requested." }, "202": { "description": "Payment confirmation pending. Poll the same order; do not send a second payment." }, "402": { "description": "Exact x402 payment challenge with frozen price, terms and expiry. No paid result delivered.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64 x402 v2 payment requirements" } } } }, "description": "Read /api/v1/offers/snapshot first for public price, access and availability metadata. Authentication errors include this URL as offer_url and in Link rel=describedby. Only an eligible authenticated live request can receive a payable x402 challenge." } }, "/api/v1/changes": { "get": { "operationId": "purchase_changes", "summary": "Evidence purchase with explicit mode and current eligibility checks", "security": [ { "AgentKey": [] } ], "parameters": [ { "in": "header", "name": "X-ALPNAI-Mode", "required": true, "schema": { "type": "string", "enum": [ "sandbox", "live" ] }, "description": "Use live explicitly for x402. Commercial activation, owner mandate and billing eligibility are required." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date" } }, { "name": "X-AlpNAI-Mandate", "in": "header", "required": false, "description": "Required in live mode: an active owner-authorized mandate for this agent.", "schema": { "type": "string", "pattern": "^[-a-zA-Z0-9]{8,80}$" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 signed exact payment payload. Only submit after checking the original 402 quote and owner wallet policy. Never send a private key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sandbox receipt, or a finalized live receipt with its result. Inspect settled and network." }, "400": { "description": "Invalid input" }, "401": { "description": "Unauthorized agent" }, "403": { "description": "Budget exhausted" }, "409": { "description": "Idempotency conflict" }, "503": { "description": "Commerce unavailable or billing qualification required; no payment requested." }, "202": { "description": "Payment confirmation pending. Poll the same order; do not send a second payment." }, "402": { "description": "Exact x402 payment challenge with frozen price, terms and expiry. No paid result delivered.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64 x402 v2 payment requirements" } } } }, "description": "Read /api/v1/offers/changes first for public price, access and availability metadata. Authentication errors include this URL as offer_url and in Link rel=describedby. Only an eligible authenticated live request can receive a payable x402 challenge." } }, "/api/v1/evidence": { "get": { "operationId": "purchase_evidence", "summary": "Evidence purchase with explicit mode and current eligibility checks", "security": [ { "AgentKey": [] } ], "parameters": [ { "in": "header", "name": "X-ALPNAI-Mode", "required": true, "schema": { "type": "string", "enum": [ "sandbox", "live" ] }, "description": "Use live explicitly for x402. Commercial activation, owner mandate and billing eligibility are required." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,100}$" } }, { "name": "X-AlpNAI-Mandate", "in": "header", "required": false, "description": "Required in live mode: an active owner-authorized mandate for this agent.", "schema": { "type": "string", "pattern": "^[-a-zA-Z0-9]{8,80}$" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 signed exact payment payload. Only submit after checking the original 402 quote and owner wallet policy. Never send a private key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sandbox receipt, or a finalized live receipt with its result. Inspect settled and network." }, "400": { "description": "Invalid input" }, "401": { "description": "Unauthorized agent" }, "403": { "description": "Budget exhausted" }, "409": { "description": "Idempotency conflict" }, "503": { "description": "Commerce unavailable or billing qualification required; no payment requested." }, "202": { "description": "Payment confirmation pending. Poll the same order; do not send a second payment." }, "402": { "description": "Exact x402 payment challenge with frozen price, terms and expiry. No paid result delivered.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64 x402 v2 payment requirements" } } } }, "description": "Read /api/v1/offers/evidence first for public price, access and availability metadata. Authentication errors include this URL as offer_url and in Link rel=describedby. Only an eligible authenticated live request can receive a payable x402 challenge." } }, "/api/v1/catalog": { "get": { "operationId": "get_catalog", "summary": "Free catalog", "responses": { "200": { "description": "JSON data" } } } }, "/api/v1/sample": { "get": { "operationId": "get_sample", "summary": "Free sample", "responses": { "200": { "description": "JSON data" } } } }, "/api/v1/spend-proof": { "post": { "summary": "Free audit of cost per successful agent task. No payment and no trace persistence.", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 128 UTF-16 code units." }, "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 10000, "description": "USD cost of this attempt. At most six decimal places; the engine verifies whole micro-USD using floating-point tolerance. No multipleOf keyword is used, to avoid rejecting valid JSON decimals." }, "success": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Recorded attempt duration in milliseconds; decimals are accepted. Omit if not measured." } }, "required": [ "task_id", "workflow", "variant", "cost_usd", "success" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [], "additionalProperties": false } }, "required": [ "runs" ], "additionalProperties": false, "title": "ALPNAI recorded agent attempts", "description": "Recorded attempts, not prompts or secrets. Identical rows count as separate attempts. All three analysis tools accept this same input. The runtime validator additionally enforces six-decimal micro-USD precision, the same task_id belonging to one workflow, one workflow when monthlyTasks is given, and UTF-16 length limits. HTTP body limit: 512000 UTF-8 bytes." } } } }, "responses": { "200": { "description": "Conditional analysis, no realized-savings or deployment claim.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "const": "free_audit" }, "payment_required": { "type": "boolean", "const": false }, "persisted": { "type": "boolean", "const": false }, "data": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "purpose": { "type": "string", "const": "cost_per_successful_agent_task_audit" }, "data_provenance": { "type": "string", "const": "user_supplied_not_verified" }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [ "minSamples", "minSuccessRate", "maxSuccessRateDrop" ], "additionalProperties": true }, "input_attempt_records": { "type": "integer", "minimum": 1, "maximum": 1000 }, "experimental_bias_control": { "type": "string", "const": "unknown" }, "automatic_deployment_authorized": { "type": "boolean", "const": false }, "methodology": { "type": "object", "properties": { "logical_task_key": { "type": "array", "items": { "type": "string" }, "minItems": 3, "maxItems": 3 }, "success": { "type": "string" }, "duplicates": { "type": "string" }, "latency": { "type": "string" }, "quality": { "type": "string" }, "uncertainty": { "type": "string" }, "missing_costs": { "type": "string" } }, "required": [ "logical_task_key", "success", "duplicates", "latency", "quality", "uncertainty", "missing_costs" ], "additionalProperties": true }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "baseline": { "anyOf": [ { "type": "object", "properties": { "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "successful_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "cost_per_task_usd": { "type": "number", "minimum": 0 }, "cost_per_successful_task_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "success_rate_interval_95_wilson": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2 }, "p95_recorded_attempt_latency_per_task_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "latency_complete": { "type": "boolean" } }, "required": [ "tasks", "attempts", "retry_attempts", "successful_tasks", "total_cost_usd", "cost_per_task_usd", "cost_per_successful_task_usd", "success_rate", "success_rate_interval_95_wilson", "p95_recorded_attempt_latency_per_task_ms", "latency_complete" ], "additionalProperties": true }, { "type": "null" } ] }, "candidate": { "anyOf": [ { "type": "object", "properties": { "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "successful_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "cost_per_task_usd": { "type": "number", "minimum": 0 }, "cost_per_successful_task_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "success_rate_interval_95_wilson": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2 }, "p95_recorded_attempt_latency_per_task_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "latency_complete": { "type": "boolean" } }, "required": [ "tasks", "attempts", "retry_attempts", "successful_tasks", "total_cost_usd", "cost_per_task_usd", "cost_per_successful_task_usd", "success_rate", "success_rate_interval_95_wilson", "p95_recorded_attempt_latency_per_task_ms", "latency_complete" ], "additionalProperties": true }, { "type": "null" } ] }, "comparison": { "type": "object", "properties": { "matched_task_ids": { "type": "integer", "minimum": 0, "maximum": 1000 }, "baseline_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "candidate_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "same_task_set": { "type": "boolean" } }, "required": [ "matched_task_ids", "baseline_only_tasks", "candidate_only_tasks", "same_task_set" ], "additionalProperties": true }, "gates": { "type": "object", "properties": { "both_variants": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "minimum_distinct_tasks_per_variant": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "same_task_set": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "observed_success_rate": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "recorded_latency": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "lower_cost_per_successful_task": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "experimental_bias_control": { "type": "string", "const": "unknown" } }, "required": [ "both_variants", "minimum_distinct_tasks_per_variant", "same_task_set", "observed_success_rate", "recorded_latency", "lower_cost_per_successful_task", "experimental_bias_control" ], "additionalProperties": true }, "decision": { "type": "string", "enum": [ "missing_comparison", "collect_more_data", "quality_regression", "latency_data_required", "latency_regression", "no_economic_advantage", "candidate_for_controlled_trial" ] }, "automatic_deployment_authorized": { "type": "boolean", "const": false }, "realized_savings_usd": { "type": "null" }, "opportunity_monthly": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "conditional_projection_not_realized" }, "basis": { "type": "string", "const": "same_expected_successful_task_volume" }, "currency": { "type": "string", "const": "USD" }, "period": { "type": "string", "const": "month" }, "baseline_launched_tasks_per_month": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "expected_successful_tasks_per_month": { "type": "number", "minimum": 0 }, "candidate_expected_launched_tasks_per_month": { "type": "number", "minimum": 0 }, "baseline_expected_cost_usd": { "type": "number", "minimum": 0 }, "candidate_expected_cost_usd": { "type": "number", "minimum": 0 }, "potential_cost_difference_usd": { "type": "number", "minimum": 0 }, "excludes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "conditions": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "status", "basis", "currency", "period", "baseline_launched_tasks_per_month", "expected_successful_tasks_per_month", "candidate_expected_launched_tasks_per_month", "baseline_expected_cost_usd", "candidate_expected_cost_usd", "potential_cost_difference_usd", "excludes", "conditions" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "workflow", "baseline", "candidate", "comparison", "gates", "decision", "automatic_deployment_authorized", "realized_savings_usd", "opportunity_monthly" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "purpose", "data_provenance", "config", "input_attempt_records", "experimental_bias_control", "automatic_deployment_authorized", "methodology", "workflows" ], "additionalProperties": true } }, "required": [ "mode", "payment_required", "persisted", "data" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Active test agent key required" }, "413": { "description": "512000-byte request limit exceeded" } } } }, "/api/v1/latency": { "post": { "summary": "Analyze recorded task durations, P50, P95 and retries", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 128 UTF-16 code units." }, "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 10000, "description": "USD cost of this attempt. At most six decimal places; the engine verifies whole micro-USD using floating-point tolerance. No multipleOf keyword is used, to avoid rejecting valid JSON decimals." }, "success": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Recorded attempt duration in milliseconds; decimals are accepted. Omit if not measured." } }, "required": [ "task_id", "workflow", "variant", "cost_usd", "success" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [], "additionalProperties": false } }, "required": [ "runs" ], "additionalProperties": false, "title": "ALPNAI recorded agent attempts", "description": "Recorded attempts, not prompts or secrets. Identical rows count as separate attempts. All three analysis tools accept this same input. The runtime validator additionally enforces six-decimal micro-USD precision, the same task_id belonging to one workflow, one workflow when monthlyTasks is given, and UTF-16 length limits. HTTP body limit: 512000 UTF-8 bytes." } } } }, "responses": { "200": { "description": "Analysis computed from supplied traces; no payment, no application storage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "const": "free_audit" }, "payment_required": { "type": "boolean", "const": false }, "persisted": { "type": "boolean", "const": false }, "data": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "measurement": { "type": "string", "const": "summed_recorded_attempt_durations_per_task" }, "percentile_method": { "type": "string", "const": "nearest_rank" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "recorded_attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "duration_coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "p50_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "p95_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "max_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "threshold_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "within_p95_threshold": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "workflow", "variant", "tasks", "recorded_attempts", "retry_attempts", "duration_coverage", "p50_ms", "p95_ms", "max_ms", "threshold_ms", "within_p95_threshold" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "measurement", "percentile_method", "groups" ], "additionalProperties": true } }, "required": [ "mode", "payment_required", "persisted", "data" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Active test agent key required" }, "413": { "description": "512000-byte request limit exceeded" } }, "operationId": "analyzeLatency" } }, "/api/v1/quality-gate": { "post": { "summary": "Check quality, cost and recorded latency thresholds", "security": [ { "agentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 128 UTF-16 code units." }, "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 10000, "description": "USD cost of this attempt. At most six decimal places; the engine verifies whole micro-USD using floating-point tolerance. No multipleOf keyword is used, to avoid rejecting valid JSON decimals." }, "success": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Recorded attempt duration in milliseconds; decimals are accepted. Omit if not measured." } }, "required": [ "task_id", "workflow", "variant", "cost_usd", "success" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [], "additionalProperties": false } }, "required": [ "runs" ], "additionalProperties": false, "title": "ALPNAI recorded agent attempts", "description": "Recorded attempts, not prompts or secrets. Identical rows count as separate attempts. All three analysis tools accept this same input. The runtime validator additionally enforces six-decimal micro-USD precision, the same task_id belonging to one workflow, one workflow when monthlyTasks is given, and UTF-16 length limits. HTTP body limit: 512000 UTF-8 bytes." } } } }, "responses": { "200": { "description": "Analysis computed from supplied traces; no payment, no application storage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "const": "free_audit" }, "payment_required": { "type": "boolean", "const": false }, "persisted": { "type": "boolean", "const": false }, "data": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [ "minSamples", "minSuccessRate", "maxSuccessRateDrop" ], "additionalProperties": true }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "comparison": { "type": "object", "properties": { "matched_task_ids": { "type": "integer", "minimum": 0, "maximum": 1000 }, "baseline_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "candidate_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "same_task_set": { "type": "boolean" } }, "required": [ "matched_task_ids", "baseline_only_tasks", "candidate_only_tasks", "same_task_set" ], "additionalProperties": true }, "gates": { "type": "object", "properties": { "both_variants": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "minimum_distinct_tasks_per_variant": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "same_task_set": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "observed_success_rate": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "recorded_latency": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "lower_cost_per_successful_task": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "experimental_bias_control": { "type": "string", "const": "unknown" } }, "required": [ "both_variants", "minimum_distinct_tasks_per_variant", "same_task_set", "observed_success_rate", "recorded_latency", "lower_cost_per_successful_task", "experimental_bias_control" ], "additionalProperties": true }, "decision": { "type": "string", "enum": [ "missing_comparison", "collect_more_data", "quality_regression", "latency_data_required", "latency_regression", "no_economic_advantage", "candidate_for_controlled_trial" ] }, "baseline_success": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "candidate_success": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "automatic_deployment_authorized": { "type": "boolean", "const": false } }, "required": [ "workflow", "comparison", "gates", "decision", "baseline_success", "candidate_success", "automatic_deployment_authorized" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "config", "workflows" ], "additionalProperties": true } }, "required": [ "mode", "payment_required", "persisted", "data" ], "additionalProperties": true } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Active test agent key required" }, "413": { "description": "512000-byte request limit exceeded" } }, "operationId": "checkQuality" } }, "/api/v1/project-reports": { "post": { "operationId": "save_project_report", "summary": "Calculate and save one report in the owner-authorized project", "description": "Compute and save an aggregate performance report in the fixed Projects destination authorized by the account owner. Uses the existing free or paid report allowance. Requires an active agent key and explicit owner write permission. Reuse request_id with identical content to retry within the same permission grant. No report reading, deletion, subscription or payment authorization. Send measurements without secrets. A repeated identical request consumes no additional report quota. Changing or re-enabling the grant creates a new request namespace. No automatic paid upgrade or overage. The successful response contains no private report history.", "security": [ { "AgentKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "input": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 128 UTF-16 code units." }, "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 10000, "description": "USD cost of this attempt. At most six decimal places; the engine verifies whole micro-USD using floating-point tolerance. No multipleOf keyword is used, to avoid rejecting valid JSON decimals." }, "success": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Recorded attempt duration in milliseconds; decimals are accepted. Omit if not measured." } }, "required": [ "task_id", "workflow", "variant", "cost_usd", "success" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [], "additionalProperties": false } }, "required": [ "runs" ], "additionalProperties": false, "title": "ALPNAI recorded agent attempts", "description": "Recorded attempts, not prompts or secrets. Identical rows count as separate attempts. All three analysis tools accept this same input. The runtime validator additionally enforces six-decimal micro-USD precision, the same task_id belonging to one workflow, one workflow when monthlyTasks is given, and UTF-16 length limits. HTTP body limit: 512000 UTF-8 bytes." } }, "required": [ "request_id", "title", "input" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Saved or replayed report identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "replayed": { "type": "boolean" }, "saved": { "const": true }, "persistence": { "const": "computed_summary" }, "payment_authorized": { "const": false } }, "required": [ "id", "replayed", "saved", "persistence", "payment_authorized" ] } } } }, "400": { "description": "Invalid measurements or request" }, "401": { "description": "Missing or revoked agent key" }, "403": { "description": "Owner grant missing or revoked" }, "409": { "description": "Report quota exhausted, replay conflict or deleted report" }, "413": { "description": "Request too large" }, "503": { "description": "Service temporarily unavailable; retry with the same request ID and content" } } } }, "/api/v1/performance-sample": { "get": { "operationId": "getPerformanceSample", "summary": "Evaluate the performance contract without an account or payment", "description": "Returns fixed, explicitly synthetic input and actual computed cost, latency and quality results. No request body, authentication, storage or external model call. Recalculate before using authenticated analyses.", "security": [], "responses": { "200": { "description": "Synthetic demonstration, not measured customer savings or a paid-flow test.", "content": { "application/json": { "schema": { "type": "object", "required": [ "contract", "contract_version", "synthetic", "authentication_required", "payment_required", "input", "results" ], "properties": { "contract": { "const": "alpnai.performance-sample" }, "contract_version": { "const": "1.0.0" }, "synthetic": { "const": true }, "authentication_required": { "const": false }, "payment_required": { "const": false }, "input": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 128 UTF-16 code units." }, "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "cost_usd": { "type": "number", "minimum": 0, "maximum": 10000, "description": "USD cost of this attempt. At most six decimal places; the engine verifies whole micro-USD using floating-point tolerance. No multipleOf keyword is used, to avoid rejecting valid JSON decimals." }, "success": { "type": "boolean" }, "latency_ms": { "type": "number", "minimum": 0, "maximum": 86400000, "description": "Recorded attempt duration in milliseconds; decimals are accepted. Omit if not measured." } }, "required": [ "task_id", "workflow", "variant", "cost_usd", "success" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [], "additionalProperties": false } }, "required": [ "runs" ], "additionalProperties": false, "title": "ALPNAI recorded agent attempts", "description": "Recorded attempts, not prompts or secrets. Identical rows count as separate attempts. All three analysis tools accept this same input. The runtime validator additionally enforces six-decimal micro-USD precision, the same task_id belonging to one workflow, one workflow when monthlyTasks is given, and UTF-16 length limits. HTTP body limit: 512000 UTF-8 bytes." }, "results": { "type": "object", "properties": { "cost": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "purpose": { "type": "string", "const": "cost_per_successful_agent_task_audit" }, "data_provenance": { "type": "string", "const": "user_supplied_not_verified" }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [ "minSamples", "minSuccessRate", "maxSuccessRateDrop" ], "additionalProperties": true }, "input_attempt_records": { "type": "integer", "minimum": 1, "maximum": 1000 }, "experimental_bias_control": { "type": "string", "const": "unknown" }, "automatic_deployment_authorized": { "type": "boolean", "const": false }, "methodology": { "type": "object", "properties": { "logical_task_key": { "type": "array", "items": { "type": "string" }, "minItems": 3, "maxItems": 3 }, "success": { "type": "string" }, "duplicates": { "type": "string" }, "latency": { "type": "string" }, "quality": { "type": "string" }, "uncertainty": { "type": "string" }, "missing_costs": { "type": "string" } }, "required": [ "logical_task_key", "success", "duplicates", "latency", "quality", "uncertainty", "missing_costs" ], "additionalProperties": true }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "baseline": { "anyOf": [ { "type": "object", "properties": { "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "successful_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "cost_per_task_usd": { "type": "number", "minimum": 0 }, "cost_per_successful_task_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "success_rate_interval_95_wilson": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2 }, "p95_recorded_attempt_latency_per_task_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "latency_complete": { "type": "boolean" } }, "required": [ "tasks", "attempts", "retry_attempts", "successful_tasks", "total_cost_usd", "cost_per_task_usd", "cost_per_successful_task_usd", "success_rate", "success_rate_interval_95_wilson", "p95_recorded_attempt_latency_per_task_ms", "latency_complete" ], "additionalProperties": true }, { "type": "null" } ] }, "candidate": { "anyOf": [ { "type": "object", "properties": { "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "successful_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "total_cost_usd": { "type": "number", "minimum": 0 }, "cost_per_task_usd": { "type": "number", "minimum": 0 }, "cost_per_successful_task_usd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "success_rate": { "type": "number", "minimum": 0, "maximum": 1 }, "success_rate_interval_95_wilson": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 }, "minItems": 2, "maxItems": 2 }, "p95_recorded_attempt_latency_per_task_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "latency_complete": { "type": "boolean" } }, "required": [ "tasks", "attempts", "retry_attempts", "successful_tasks", "total_cost_usd", "cost_per_task_usd", "cost_per_successful_task_usd", "success_rate", "success_rate_interval_95_wilson", "p95_recorded_attempt_latency_per_task_ms", "latency_complete" ], "additionalProperties": true }, { "type": "null" } ] }, "comparison": { "type": "object", "properties": { "matched_task_ids": { "type": "integer", "minimum": 0, "maximum": 1000 }, "baseline_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "candidate_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "same_task_set": { "type": "boolean" } }, "required": [ "matched_task_ids", "baseline_only_tasks", "candidate_only_tasks", "same_task_set" ], "additionalProperties": true }, "gates": { "type": "object", "properties": { "both_variants": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "minimum_distinct_tasks_per_variant": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "same_task_set": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "observed_success_rate": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "recorded_latency": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "lower_cost_per_successful_task": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "experimental_bias_control": { "type": "string", "const": "unknown" } }, "required": [ "both_variants", "minimum_distinct_tasks_per_variant", "same_task_set", "observed_success_rate", "recorded_latency", "lower_cost_per_successful_task", "experimental_bias_control" ], "additionalProperties": true }, "decision": { "type": "string", "enum": [ "missing_comparison", "collect_more_data", "quality_regression", "latency_data_required", "latency_regression", "no_economic_advantage", "candidate_for_controlled_trial" ] }, "automatic_deployment_authorized": { "type": "boolean", "const": false }, "realized_savings_usd": { "type": "null" }, "opportunity_monthly": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "conditional_projection_not_realized" }, "basis": { "type": "string", "const": "same_expected_successful_task_volume" }, "currency": { "type": "string", "const": "USD" }, "period": { "type": "string", "const": "month" }, "baseline_launched_tasks_per_month": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "expected_successful_tasks_per_month": { "type": "number", "minimum": 0 }, "candidate_expected_launched_tasks_per_month": { "type": "number", "minimum": 0 }, "baseline_expected_cost_usd": { "type": "number", "minimum": 0 }, "candidate_expected_cost_usd": { "type": "number", "minimum": 0 }, "potential_cost_difference_usd": { "type": "number", "minimum": 0 }, "excludes": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "conditions": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "status", "basis", "currency", "period", "baseline_launched_tasks_per_month", "expected_successful_tasks_per_month", "candidate_expected_launched_tasks_per_month", "baseline_expected_cost_usd", "candidate_expected_cost_usd", "potential_cost_difference_usd", "excludes", "conditions" ], "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "workflow", "baseline", "candidate", "comparison", "gates", "decision", "automatic_deployment_authorized", "realized_savings_usd", "opportunity_monthly" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "purpose", "data_provenance", "config", "input_attempt_records", "experimental_bias_control", "automatic_deployment_authorized", "methodology", "workflows" ], "additionalProperties": true }, "latency": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "measurement": { "type": "string", "const": "summed_recorded_attempt_durations_per_task" }, "percentile_method": { "type": "string", "const": "nearest_rank" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "variant": { "type": "string", "enum": [ "baseline", "candidate" ] }, "tasks": { "type": "integer", "minimum": 1, "maximum": 1000 }, "recorded_attempts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "retry_attempts": { "type": "integer", "minimum": 0, "maximum": 999 }, "duration_coverage": { "type": "number", "minimum": 0, "maximum": 1 }, "p50_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "p95_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "max_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "threshold_ms": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 86400000000 }, { "type": "null" } ] }, "within_p95_threshold": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "workflow", "variant", "tasks", "recorded_attempts", "retry_attempts", "duration_coverage", "p50_ms", "p95_ms", "max_ms", "threshold_ms", "within_p95_threshold" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "measurement", "percentile_method", "groups" ], "additionalProperties": true }, "quality": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "1.0.0" }, "config": { "type": "object", "properties": { "minSamples": { "type": "integer", "minimum": 2, "maximum": 500, "default": 30 }, "minSuccessRate": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.95 }, "maxSuccessRateDrop": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.02 }, "maxP95LatencyMs": { "type": "number", "minimum": 0, "maximum": 86400000000 }, "monthlyTasks": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Baseline logical tasks launched per month; the engine requires exactly one workflow if supplied." } }, "required": [ "minSamples", "minSuccessRate", "maxSuccessRateDrop" ], "additionalProperties": true }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?![\\s\\S]*\\s$)[^\\u0000-\\u001F\\u007F]+$", "description": "Nonempty, no control characters or surrounding whitespace. The engine additionally enforces at most 80 UTF-16 code units." }, "comparison": { "type": "object", "properties": { "matched_task_ids": { "type": "integer", "minimum": 0, "maximum": 1000 }, "baseline_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "candidate_only_tasks": { "type": "integer", "minimum": 0, "maximum": 1000 }, "same_task_set": { "type": "boolean" } }, "required": [ "matched_task_ids", "baseline_only_tasks", "candidate_only_tasks", "same_task_set" ], "additionalProperties": true }, "gates": { "type": "object", "properties": { "both_variants": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "minimum_distinct_tasks_per_variant": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "same_task_set": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "observed_success_rate": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "recorded_latency": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "lower_cost_per_successful_task": { "type": "string", "enum": [ "pass", "fail", "unknown", "not_requested" ] }, "experimental_bias_control": { "type": "string", "const": "unknown" } }, "required": [ "both_variants", "minimum_distinct_tasks_per_variant", "same_task_set", "observed_success_rate", "recorded_latency", "lower_cost_per_successful_task", "experimental_bias_control" ], "additionalProperties": true }, "decision": { "type": "string", "enum": [ "missing_comparison", "collect_more_data", "quality_regression", "latency_data_required", "latency_regression", "no_economic_advantage", "candidate_for_controlled_trial" ] }, "baseline_success": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "candidate_success": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "automatic_deployment_authorized": { "type": "boolean", "const": false } }, "required": [ "workflow", "comparison", "gates", "decision", "baseline_success", "candidate_success", "automatic_deployment_authorized" ], "additionalProperties": true }, "minItems": 1, "maxItems": 1000 } }, "required": [ "schema_version", "config", "workflows" ], "additionalProperties": true } }, "required": [ "cost", "latency", "quality" ], "additionalProperties": true } } } } } } } } }, "/api/v1/offers/{product}": { "get": { "operationId": "get_public_offer", "summary": "Inspect product access, price and availability without authentication or payment", "description": "This ALPNAI descriptor is not an x402 PaymentRequired response. Never sign or transfer funds using it. Follow the access prerequisites to request an authenticated, order-bound quote when commercial routes are open.", "security": [], "parameters": [ { "in": "path", "name": "product", "required": true, "schema": { "type": "string", "enum": [ "snapshot", "changes", "evidence" ] } } ], "responses": { "200": { "description": "Public service metadata; no order, billing verification, signature or payment is created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "id", "purchase", "pricing", "discovery", "delivery" ], "properties": { "kind": { "const": "service_offer" }, "id": { "type": "string", "enum": [ "snapshot", "changes", "evidence" ] }, "purchase": { "type": "object", "required": [ "route_enabled", "mainnet_enabled", "account_eligibility_checked", "anonymous_purchase_supported" ], "properties": { "route_enabled": { "type": "boolean" }, "mainnet_enabled": { "type": "boolean" }, "account_eligibility_checked": { "const": false }, "anonymous_purchase_supported": { "const": false } } }, "discovery": { "type": "object", "required": [ "payment_required", "payment_authorized", "product_data_included" ], "properties": { "payment_required": { "const": false }, "payment_authorized": { "const": false }, "product_data_included": { "const": false } } }, "pricing": { "type": "object" }, "delivery": { "type": "object" } } } } } }, "400": { "description": "Query parameters are not accepted." }, "404": { "description": "Unknown product." } } } }, "/api/v1/orders/{order_id}": { "get": { "operationId": "getOrder", "summary": "Follow an existing authorized order without submitting another payment", "description": "Requires the original agent key. May record finalized on-chain proof or cancel an expired never-submitted reservation, releasing its reserved budget once. No new signature or settlement is submitted. Works while new purchases are paused. MCP equivalent: get_order with order_id.", "security": [ { "AgentKey": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[-A-Za-z0-9]{8,80}$" } } ], "responses": { "200": { "description": "Quoted status, or confirmed receipt and original JSON deliverable. Only settled:true indicates paid delivery." }, "202": { "description": "Original payment remains pending. Wait for Retry-After and query this same order again." }, "401": { "description": "Active agent key required." }, "403": { "description": "Request origin rejected." }, "404": { "description": "Order absent or not owned by this agent." }, "409": { "description": "Cancelled before ALPNAI claimed submission; payment_required:false." }, "503": { "description": "Order status temporarily unavailable; keep the original order identity." } } } } }, "components": { "securitySchemes": { "AgentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "alp_test" }, "agentKey": { "type": "http", "scheme": "bearer" } } } }