{ "openapi": "3.0.3", "info": { "title": "Veyra Agent API", "version": "0.1.0-beta.2", "description": "Machine API for Veyra on Arc Testnet \u2014 verified workflows, evidence-weighted agent reputation, Trust Gate policy decisions, counterparty selection, ERC-8183 independent evaluation, continuous trust monitoring, and Project 360.", "contact": { "name": "Veyra Team", "url": "https://github.com/mioku50/Veyra" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://agent-commerce-six.vercel.app", "description": "Arc Testnet Live Production Server" }, { "url": "http://localhost:3000", "description": "Local Development Server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/reputation/v1/agents/{agentId}": { "get": { "summary": "Get Evidence-Weighted Agent Reputation", "description": "Returns deterministic trust score (0-100), coverage, 6-dimension breakdown, and explanations for an AI agent on Arc Testnet.", "operationId": "getAgentReputation", "security": [], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ERC-8004 Agent ID or canonical identifier" } ], "responses": { "200": { "description": "Agent reputation object", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "trustScore": { "type": "integer", "example": 86 }, "confidence": { "type": "string", "example": "High" }, "coverage": { "type": "number", "example": 82 }, "statusLabel": { "type": "string", "example": "Strong" }, "dimensions": { "type": "object" }, "topPositiveEvidence": { "type": "array", "items": { "type": "string" } }, "riskSignals": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/erc8183/v1/evaluator": { "get": { "summary": "Get Veyra ERC-8183 Evaluator Metadata", "description": "Returns public capability metadata for the canonical Veyra ERC-8183 evaluator on Arc Testnet.", "operationId": "getErc8183Evaluator", "security": [], "responses": { "200": { "description": "Safe public evaluator metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "standard": { "type": "string", "example": "ERC-8183" }, "network": { "type": "string", "example": "arc-testnet" }, "chainId": { "type": "integer", "example": 5042002 }, "status": { "type": "string", "enum": [ "active", "paused" ], "example": "active" }, "evaluatorAddress": { "type": "string", "example": "0x0d2c04580e081e222bbe5bf9818af337e2633eb7" }, "commerceAddress": { "type": "string", "example": "0x0747EEf0706327138c69792bF28Cd525089e4583" }, "policy": { "type": "string", "example": "structured-deliverable-v1" } }, "required": [ "standard", "network", "chainId", "status", "evaluatorAddress", "commerceAddress", "policy" ] } } } } } } }, "/api/agent/v1/workflows": { "get": { "summary": "List available workflows", "description": "Returns available workflow templates, input schemas, list prices, and Arc Testnet metadata. Requires `workflows:read` credential scope.", "operationId": "listWorkflows", "responses": { "200": { "description": "List of available workflows", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "example": "1" }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowTemplate" } } }, "required": [ "version", "workflows" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/v1/project-360/discoveries": { "post": { "summary": "Run free Project 360 discovery", "description": "Scans one validated public identifier for Project 360 source candidates. Discovery is free and non-transactional. Every candidate is returned with included=false and cannot enter a paid module without a later explicit selection. Requires quotes:create scope and Idempotency-Key.", "operationId": "discoverProject360", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360DiscoveryRequest" } } } }, "responses": { "200": { "description": "Idempotent discovery replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360DiscoveryEnvelope" } } } }, "201": { "description": "Discovery completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360DiscoveryEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/project-360/discoveries/{discoveryId}": { "get": { "summary": "Get Project 360 discovery", "description": "Returns a discovery only to the credential that created it. Requires results:read scope.", "operationId": "getProject360Discovery", "parameters": [ { "name": "discoveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dsc_[0-9a-f]{20}$" } } ], "responses": { "200": { "description": "Credential-scoped discovery", "content": { "application/json": { "schema": { "type": "object", "required": [ "discovery" ], "properties": { "discovery": { "$ref": "#/components/schemas/Project360Discovery" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/project-360/discoveries/{discoveryId}/quote": { "post": { "summary": "Create an immutable Project 360 quote", "description": "Binds explicit candidate IDs and modules to the current discovery revision. The response lists every module price, total price, expected coverage, and incomplete-data warnings. No unselected candidate is included. Requires quotes:create scope and Idempotency-Key.", "operationId": "createProject360Quote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "discoveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^dsc_[0-9a-f]{20}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360QuoteRequest" } } } }, "responses": { "200": { "description": "Idempotent quote replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360QuoteResponse" } } } }, "201": { "description": "Immutable quote created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project360QuoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/quotes": { "post": { "summary": "Create workflow quote", "description": "Generates an immutable workflow quote with list price and required payment details. Requires `quotes:create` scope and `Idempotency-Key` header.", "operationId": "createQuote", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowQuoteRequest" } } } }, "responses": { "200": { "description": "Quote created or returned from cache (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowQuoteResponse" } } } }, "201": { "description": "Quote successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowQuoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/runs": { "post": { "summary": "Launch workflow execution", "description": "Launches execution for a valid quote. Supports sponsored quota or paid x402 transaction hash. Requires `runs:create` scope and `Idempotency-Key` header.", "operationId": "launchRun", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunLaunchRequest" } } } }, "responses": { "201": { "description": "Run queued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunLaunchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/runs/{runId}": { "get": { "summary": "Poll run execution status", "description": "Retrieves the current execution status, stage, progress, and reportId upon completion. Scoped to credential owner. Requires `results:read` scope.", "operationId": "getRunStatus", "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "The run identifier returned from POST /api/agent/v1/runs", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current run execution status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/v1/reports/{reportId}": { "get": { "summary": "Retrieve structured report", "description": "Returns the completed structured report and Arc verification proofs. Supports `Accept: application/json` or `Accept: text/markdown`. Requires `results:read` scope.", "operationId": "getReport", "parameters": [ { "name": "reportId", "in": "path", "required": true, "description": "The report identifier (matches runId)", "schema": { "type": "string" } }, { "name": "Accept", "in": "header", "required": false, "description": "Media type negotiation: `application/json` (default) or `text/markdown`", "schema": { "type": "string", "enum": [ "application/json", "text/markdown" ] } } ], "responses": { "200": { "description": "Structured JSON report or formatted Markdown text", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StructuredReportResponse" }, { "$ref": "#/components/schemas/AgentTrustReportResponse" }, { "$ref": "#/components/schemas/Project360ReportResponse" } ] } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Report not ready yet (`report_not_ready`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/v1/watchlists": { "get": { "summary": "List credential-scoped trust watchlists", "operationId": "listWatchlists", "description": "Lists only watchlists owned by the exact Machine API agent and credential. Requires `results:read` scope.", "responses": { "200": { "description": "Credential-scoped watchlists", "content": { "application/json": { "schema": { "type": "object", "required": [ "watchlists" ], "properties": { "watchlists": { "type": "array", "items": { "$ref": "#/components/schemas/TrustWatchlist" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "summary": "Create a trust watchlist", "operationId": "createWatchlist", "description": "Saves public Agent Trust Report input for manual, daily, or weekly rechecks. Requires `runs:create` scope and `Idempotency-Key`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "properties": { "label": { "type": "string", "minLength": 2, "maxLength": 100 }, "input": { "$ref": "#/components/schemas/AgentTrustReportInput" }, "cadence": { "type": "string", "enum": [ "manual", "daily", "weekly" ], "default": "manual" }, "visibility": { "type": "string", "enum": [ "private", "public" ], "default": "private", "description": "Explicit publication control. Omitted Machine API watchlists remain private." } } } } } }, "responses": { "200": { "description": "Existing idempotent watchlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustWatchlist" } } } }, "201": { "description": "Watchlist created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustWatchlist" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/agent/v1/watchlists/{watchlistId}": { "get": { "summary": "Retrieve trust history", "operationId": "getWatchlist", "description": "Returns the current report, deterministic delta, and Arc proof for every snapshot. An unowned watchlist returns 404.", "parameters": [ { "name": "watchlistId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wtl_[0-9a-f]{20}$" } } ], "responses": { "200": { "description": "Trust monitoring history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustHistory" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/agent/v1/watchlists/{watchlistId}/rechecks": { "post": { "summary": "Create an immutable recheck quote", "operationId": "createWatchlistRecheck", "description": "Creates a credential-owned Agent Trust Report quote linked to the watchlist. Launch the returned `quoteId` through POST `/api/agent/v1/runs`.", "parameters": [ { "name": "watchlistId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wtl_[0-9a-f]{20}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Existing idempotent recheck quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustRecheckQuote" } } } }, "201": { "description": "Recheck quote created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustRecheckQuote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/monitoring/public/{publicId}": { "get": { "summary": "Retrieve a public Veyra Trust Profile", "operationId": "getPublicTrustProfile", "security": [], "description": "Returns only canonical public trust information and Arc proofs. Private or unknown profiles both return 404.", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" } } ], "responses": { "200": { "description": "Public trust profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTrustProfile" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/public/trust/{publicId}/status": { "get": { "summary": "Retrieve compact public Trust Profile status", "operationId": "getPublicTrustStatus", "security": [], "description": "Returns the current public score, status, latest Arc verification state, freshness, and canonical profile URL. Private and unknown profiles return the same 404.", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" } } ], "responses": { "200": { "description": "Compact public trust status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTrustStatus" } } } }, "304": { "description": "The supplied ETag is still current" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/api/trust/{publicId}/badge.svg": { "get": { "summary": "Render a public Veyra Trust SVG badge", "operationId": "getTrustBadge", "security": [], "description": "Server-rendered SVG. Use variant=score, status, or arc. Private and unknown profiles return the same 404. ETag changes with public status and snapshot freshness.", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" } }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "score", "status", "arc" ], "default": "score" } } ], "responses": { "200": { "description": "Veyra Trust SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "304": { "description": "The supplied ETag is still current" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/alerts": { "get": { "summary": "List credential-scoped trust alerts", "operationId": "listTrustAlerts", "description": "Requires the explicitly granted `alerts:read` scope. Existing credentials do not receive this permission automatically.", "responses": { "200": { "description": "Alerts and unread count", "content": { "application/json": { "schema": { "type": "object", "required": [ "alerts", "unreadCount" ], "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/TrustAlert" } }, "unreadCount": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/agent/v1/alerts/{alertId}/read": { "post": { "summary": "Mark a credential-scoped trust alert as read", "operationId": "markTrustAlertRead", "description": "Requires `alerts:write`. A foreign alert returns 404.", "parameters": [ { "name": "alertId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^evt_[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Alert state updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/webhooks": { "get": { "summary": "List credential-scoped webhook subscriptions", "operationId": "listWebhooks", "description": "Requires the explicitly granted `webhooks:read` scope.", "responses": { "200": { "description": "Webhook subscriptions", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "summary": "Create a signed webhook subscription", "operationId": "createWebhook", "description": "Requires `webhooks:write`. The HMAC secret is returned once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionInput" } } } }, "responses": { "201": { "description": "Webhook and one-time signing secret" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/webhooks/{webhookId}": { "patch": { "summary": "Update or pause a webhook", "operationId": "updateWebhook", "description": "Requires `webhooks:write`. A foreign webhook returns 404.", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Updated webhook" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Webhook deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/webhooks/{webhookId}/test": { "post": { "summary": "Schedule a signed test event", "operationId": "sendWebhookTest", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "202": { "description": "Test delivery scheduled" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/webhooks/{webhookId}/rotate-secret": { "post": { "summary": "Rotate the webhook signing secret", "operationId": "rotateWebhookSecret", "description": "Returns the new secret once. The previous secret is included in signatures for a ten-minute grace period.", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Secret rotated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/v1/webhooks/{webhookId}/deliveries": { "get": { "summary": "List sanitized webhook delivery history", "operationId": "listWebhookDeliveries", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "Delivery metadata without response bodies or secrets" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/erc8183/v1/deliverables/prepare": { "post": { "summary": "Prepare ERC-8183 Deliverable Commitment V1", "operationId": "prepareDeliverableCommitment", "description": "Computes deterministic deliverableHash and policyHash for VeyraDeliverableV1 commitment.", "responses": { "200": { "description": "Deliverable commitment hashes and submit arguments" } } } }, "/api/erc8183/v1/evaluations": { "post": { "summary": "Run offchain evaluation for ERC-8183 job", "operationId": "runErc8183Evaluation", "description": "Runs deterministic policy evaluation, creates canonical report, signs EIP-712 verdict and submits onchain settlement on Arc Testnet.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Evaluation execution status and report URL" } } } }, "/api/erc8183/v1/evaluations/{evaluationId}": { "get": { "summary": "Read ERC-8183 evaluation result", "operationId": "getErc8183Evaluation", "description": "Returns sanitized evaluation record, canonical report, and Arc settlement transaction link.", "responses": { "200": { "description": "Sanitized evaluation result" } } } }, "/api/status": { "get": { "summary": "Public Health & Network Status", "description": "Returns sanitized operational health, active Arc Testnet chain ID, and current public beta version.", "operationId": "getPublicStatus", "security": [], "responses": { "200": { "description": "Operational status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "operational" }, "network": { "type": "string", "example": "arc-testnet" }, "chainId": { "type": "integer", "example": 5042002 }, "version": { "type": "string", "example": "0.1.0-beta.1" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/trust/v1/decisions": { "post": { "summary": "Evaluate Trust Gate Decision", "description": "Evaluates a pre-transaction policy check and issues an EIP-712 signed clearance ticket if approved (ALLOW / ALLOW_WITH_LIMITS / REQUIRE_EVALUATOR / REVIEW_REQUIRED / DENY).", "operationId": "evaluateTrustDecision", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subjectAgentId", "action", "requestedValueUsdc" ], "properties": { "subjectAgentId": { "type": "string", "description": "Target Agent ID or counterparty identifier" }, "action": { "type": "string", "description": "Operation name or contract method", "example": "erc8183_job_settlement" }, "requestedValueUsdc": { "type": "number", "description": "Value of the transaction in USDC", "example": 5 }, "executorWallet": { "type": "string", "description": "Wallet executing the transaction on Arc Testnet", "example": "0x0000000000000000000000000000000000000001" }, "targetContract": { "type": "string", "description": "Destination smart contract address on Arc" }, "metadata": { "type": "object", "description": "Optional transaction context metadata" } } } } } }, "responses": { "200": { "description": "Trust decision with optional signed clearance ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "object", "properties": { "id": { "type": "string" }, "decision": { "type": "string", "enum": [ "ALLOW", "ALLOW_WITH_LIMITS", "REQUIRE_EVALUATOR", "REVIEW_REQUIRED", "DENY" ] }, "reason": { "type": "string" }, "rulesTriggered": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "clearance": { "type": "object", "description": "EIP-712 clearance message consumable by VeyraTrustGate contract" }, "signature": { "type": "string", "description": "EIP-712 signature over the clearance message" } } } } } }, "400": { "description": "Invalid input parameters" }, "503": { "description": "Trust decision service temporarily unavailable" } } } }, "/api/trust/v1/counterparties/discover": { "get": { "summary": "Discover Eligible Counterparties", "description": "Queries active and registered counterparties on Arc Testnet matching service capabilities or tags.", "operationId": "discoverCounterparties", "security": [], "parameters": [ { "name": "capability", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by capability or workflow type" }, { "name": "minReputation", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "Minimum trust score threshold" } ], "responses": { "200": { "description": "List of matching counterparties", "content": { "application/json": { "schema": { "type": "object", "properties": { "counterparties": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "name": { "type": "string" }, "walletAddress": { "type": "string" }, "reputationScore": { "type": "integer" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "/api/trust/v1/counterparties/select": { "post": { "summary": "Select Optimal Counterparty", "description": "Evaluates and ranks candidate counterparties using multi-criteria optimization across reputation, execution reliability, latency, and budget constraints.", "operationId": "selectCounterparty", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidates" ], "properties": { "taskType": { "type": "string", "example": "github_due_diligence" }, "budgetUsdc": { "type": "number", "example": 10 }, "minConfidence": { "type": "string", "example": "Medium" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "wallet": { "type": "string" }, "quotedPriceUsdc": { "type": "number" } } } } } } } } }, "responses": { "200": { "description": "Selection ranking and recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "selectionId": { "type": "string" }, "selectedAgentId": { "type": "string" }, "selectedCandidate": { "type": "object" }, "rankings": { "type": "array", "items": { "type": "object" } }, "selectionScore": { "type": "number" }, "rationale": { "type": "string" } } } } } } } } }, "/api/trust/v1/marketplace/select": { "post": { "summary": "Pre-Payment Trust Gate for Circle x402 Marketplace Endpoints", "description": "Discovers x402 endpoints from Circle's public service catalog, probes each candidate's live HTTP 402 challenge without paying, compares it against the catalog entry to detect price or payee drift, ranks the survivors through the Veyra counterparty engine, and returns an EIP-712 clearance bounding the caller's maximum exposure. Read-only: this endpoint never authorizes, quotes, or settles a payment. Marketplace settlement happens off-Arc (Circle publishes no Arc resources), while the clearance is signed against the Arc Trust Gate. Requires a Machine API credential with the quotes:create scope or a verified owner-wallet session.", "operationId": "selectMarketplaceCounterparty", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "capability", "budgetUsdc" ], "additionalProperties": false, "properties": { "capability": { "type": "string", "example": "market_research" }, "query": { "type": "string", "maxLength": 120, "description": "Free-text catalog search. Defaults to the capability." }, "task": { "type": "string", "maxLength": 1000, "description": "Optional task context. Rejected if it contains credentials." }, "budgetUsdc": { "type": "number", "example": 0.02 }, "maxPriceUsdc": { "type": "number", "example": 0.02, "description": "Per-call price ceiling applied at discovery time." }, "network": { "type": "string", "example": "eip155:8453", "description": "CAIP-2 settlement network. Arc is rejected: the Circle catalog publishes zero Arc resources." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 }, "requireExactCapability": { "type": "boolean" }, "requireCircleGateway": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Ranked marketplace candidates with a signed clearance for the winner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "selection": { "type": "object", "properties": { "selectionId": { "type": "string" }, "capability": { "type": "string" }, "network": { "type": "string" }, "settlementNetworkIsArc": { "type": "boolean", "description": "True when the sellers are paid on Arc mainnet (eip155:5042)." }, "catalogTotal": { "type": "integer" }, "discovered": { "type": "integer" }, "probed": { "type": "integer" }, "candidates": { "type": "array", "items": { "type": "object" } }, "recommendation": { "type": "object", "properties": { "granted": { "type": "boolean", "description": "False means do not pay. Fail closed." }, "reason": { "type": "string" }, "resource": { "type": "string", "nullable": true }, "payTo": { "type": "string", "nullable": true }, "priceUsdc": { "type": "number", "nullable": true }, "decision": { "type": "string", "nullable": true, "description": "A first-contact marketplace endpoint cannot reach ALLOW." }, "maxExposureUsdc": { "type": "number" }, "postCallVerificationRequired": { "type": "boolean" }, "explanation": { "type": "string" } } }, "clearance": { "type": "object", "nullable": true, "description": "EIP-712 TrustClearance bound to the winning resource, verified against the Arc Trust Gate." }, "canonicalHash": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "readOnly": { "type": "boolean", "enum": [ true ] }, "paymentCreated": { "type": "boolean", "enum": [ false ] }, "jobCreated": { "type": "boolean", "enum": [ false ] } } } } } }, "401": { "description": "Machine credential or owner session required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "400": { "description": "Invalid capability, budget, price ceiling, or unsupported network.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "502": { "description": "The Circle x402 catalog is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }, "/api/trust/v1/selections/{selectionId}": { "get": { "summary": "Retrieve Selection Result", "description": "Retrieves a previously computed counterparty selection by ID, including ranking details and proof hashes.", "operationId": "getSelectionResult", "security": [], "parameters": [ { "name": "selectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved selection result" }, "404": { "description": "Selection not found" } } } }, "/api/trust/v1/selections/{selectionId}/clearance": { "post": { "summary": "Get Signed Trust Clearance for Selection", "description": "Generates an EIP-712 signed clearance ticket for the chosen candidate in a selection result, allowing onchain execution.", "operationId": "getSelectionClearance", "security": [], "parameters": [ { "name": "selectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed clearance ticket" }, "400": { "description": "Selection is not executable" }, "404": { "description": "Selection not found" } } } }, "/api/execution/v1/mandates": { "post": { "summary": "Create Execution Mandate Challenge", "description": "Creates an EIP-712 execution mandate message challenge with spending caps and policy rules.", "operationId": "createExecutionMandate", "security": [], "responses": { "200": { "description": "Mandate EIP-712 payload ready for signing" } } }, "get": { "summary": "List Execution Mandates by Owner", "description": "Returns active and historical execution mandates for a given owner wallet.", "operationId": "listExecutionMandates", "security": [], "parameters": [ { "name": "ownerWallet", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of mandates" } } } }, "/api/execution/v1/mandates/{mandateId}/activate": { "post": { "summary": "Activate Signed Execution Mandate", "description": "Validates the EIP-712 signature against the owner wallet and activates the mandate.", "operationId": "activateExecutionMandate", "security": [], "parameters": [ { "name": "mandateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mandate activated" }, "401": { "description": "Signature verification failed" } } } }, "/api/execution/v1/prepare": { "post": { "summary": "Prepare Execution Intent", "description": "Preflights selection and policy checks, issues clearance, and prepares rail payload without committing funds.", "operationId": "prepareExecution", "security": [], "responses": { "200": { "description": "Prepared execution payload" }, "422": { "description": "Preflight revalidation failed" } } } }, "/api/execution/v1/{executionId}/execute": { "post": { "summary": "Execute Prepared Intent", "description": "Executes a prepared intent across ERC-8183 or x402, ingests reputation evidence, and updates state.", "operationId": "executePreparedIntent", "security": [], "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution result" }, "422": { "description": "Budget or preflight rejected" } } } }, "/api/execution/v1/autopilot": { "post": { "summary": "Run Autonomous Autopilot Execution", "description": "Discovers counterparty, selects winner, preflights, and executes under an active mandate.", "operationId": "runAutopilotExecution", "security": [], "responses": { "200": { "description": "Execution result" }, "503": { "description": "Autopilot disabled" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "aac_live_...", "description": "Veyra Agent API Bearer credential token (`aac_live_...`)" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key to ensure request idempotency (e.g. UUIDv4)", "schema": { "type": "string", "example": "idemp_9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" } }, "WebhookId": { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^whk_[0-9a-f]{24}$" } } }, "schemas": { "PublicTrustStatus": { "type": "object", "additionalProperties": false, "required": [ "profileId", "score", "status", "verifiedOnArc", "lastCheckedAt", "profileUrl" ], "properties": { "profileId": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" }, "score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "status": { "type": "string", "enum": [ "strong_signals", "review_recommended", "high_attention", "limited_data" ], "nullable": true }, "verifiedOnArc": { "type": "boolean" }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true }, "profileUrl": { "type": "string", "format": "uri" } } }, "TrustAlertEventType": { "type": "string", "enum": [ "trust_score_changed", "trust_status_changed", "risk_added", "risk_resolved", "verification_failed", "recheck_failed", "subject_unavailable" ] }, "TrustAlert": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "state", "message", "profileId", "profileUrl", "snapshotId", "snapshotUrl", "change", "createdAt" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{24}$" }, "type": { "$ref": "#/components/schemas/TrustAlertEventType" }, "state": { "type": "string", "enum": [ "unread", "read", "archived" ] }, "message": { "type": "string" }, "profileId": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" }, "profileUrl": { "type": "string" }, "snapshotId": { "type": "string", "nullable": true }, "snapshotUrl": { "type": "string" }, "change": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionInput": { "type": "object", "additionalProperties": false, "required": [ "name", "endpointUrl", "profileIds", "eventTypes" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "endpointUrl": { "type": "string", "format": "uri", "pattern": "^https://" }, "profileIds": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" } }, "eventTypes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/TrustAlertEventType" } } } }, "WebhookSubscription": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionInput" }, { "type": "object", "required": [ "id", "endpointDomain", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^whk_[0-9a-f]{24}$" }, "endpointDomain": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "lastSuccessfulDelivery": { "type": "string", "format": "date-time", "nullable": true }, "lastFailedDelivery": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, "MachineError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "agent_trust_input_required", "agent_not_found", "agent_access_denied", "agent_registry_unavailable", "agent_trust_service_unavailable", "contract_not_found", "contract_provider_unavailable", "endpoint_invalid", "endpoint_private_network_blocked", "endpoint_unreachable", "endpoint_response_too_large", "insufficient_trust_evidence", "invalid_wallet", "invalid_repository", "repository_not_found", "repository_inaccessible", "credential_missing", "credential_revoked", "scope_denied", "workflow_disabled", "quote_expired", "quote_not_found", "quote_already_used", "idempotency_key_missing", "idempotency_conflict", "idempotency_in_progress", "idempotency_store_unavailable", "invalid_request", "payment_required", "payment_invalid", "spending_limit_exceeded", "watchlist_invalid", "watchlist_not_found", "watchlist_limit_exceeded", "recheck_not_found", "recheck_conflict", "recheck_in_progress", "monitoring_unavailable", "run_not_found", "report_not_found", "report_not_ready", "report_generation_failed", "verification_pending", "provider_unavailable", "rate_limited", "internal_error", "api_quality_service_not_found", "api_quality_service_unavailable", "api_quality_insufficient_services", "api_quality_too_many_services", "api_quality_no_observations", "api_quality_observation_store_unavailable", "api_quality_comparison_incompatible", "api_quality_probe_budget_exceeded" ], "example": "api_quality_service_not_found", "description": "Stable Machine API error code." }, "message": { "type": "string", "example": "Enter a valid GitHub repository in owner/repository format." }, "retryable": { "type": "boolean", "example": false }, "requestId": { "type": "string", "example": "req_8f12a45b7e90" } } } } }, "WorkflowTemplate": { "type": "object", "required": [ "id", "name", "shortName", "description", "task", "estimatedUsdc", "inputSchema", "arc" ], "properties": { "id": { "type": "string", "example": "github_due_diligence" }, "name": { "type": "string", "example": "GitHub Due Diligence" }, "shortName": { "type": "string", "example": "GitHub Diligence" }, "description": { "type": "string", "example": "Comprehensive technical due diligence for open-source GitHub repositories." }, "task": { "type": "string", "example": "Evaluate repository health, architecture, security, activity, and risks" }, "estimatedUsdc": { "type": "number", "example": 0.002 }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string", "example": "object" }, "properties": { "type": "object" }, "required": { "type": "array", "items": { "type": "string" } } } }, "quoteFlow": { "type": "object", "required": [ "quote", "execution", "candidateSelectionRequired" ], "properties": { "discovery": { "type": "string" }, "quote": { "type": "string" }, "execution": { "type": "string" }, "candidateSelectionRequired": { "type": "boolean" } } }, "arc": { "type": "object", "properties": { "chainId": { "type": "number", "example": 5042002 }, "network": { "type": "string", "example": "arc-testnet" }, "asset": { "type": "string", "example": "USDC" }, "tokenAddress": { "type": "string", "example": "0x3600000000000000000000000000000000000000" } } } } }, "TrustWatchlist": { "type": "object", "required": [ "id", "profileId", "label", "input", "objectType", "visibility", "cadence", "status", "currentScore", "verificationStatus", "publicHistoryUrl", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "pattern": "^wtl_[0-9a-f]{20}$" }, "profileId": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" }, "label": { "type": "string" }, "input": { "$ref": "#/components/schemas/AgentTrustReportInput" }, "objectType": { "type": "string", "enum": [ "github_repository", "ai_agent", "wallet", "arc_contract", "service_endpoint" ] }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "cadence": { "type": "string", "enum": [ "manual", "daily", "weekly" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "nextRecheckAt": { "type": "string", "format": "date-time", "nullable": true }, "lastRecheckAt": { "type": "string", "format": "date-time", "nullable": true }, "currentScore": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "trustStatus": { "type": "string", "nullable": true }, "verificationStatus": { "type": "string", "nullable": true }, "latestSnapshotId": { "type": "string", "nullable": true }, "publicHistoryUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "TrustDeltaReport": { "type": "object", "required": [ "kind", "version", "previousSnapshotId", "currentSnapshotId", "score", "summary", "changes", "generatedAt" ], "properties": { "kind": { "type": "string", "enum": [ "trust_delta_report" ] }, "version": { "type": "integer", "enum": [ 1 ] }, "previousSnapshotId": { "type": "string", "nullable": true }, "currentSnapshotId": { "type": "string" }, "score": { "type": "object", "properties": { "before": { "type": "integer", "nullable": true }, "after": { "type": "integer", "nullable": true }, "change": { "type": "integer", "nullable": true }, "direction": { "type": "string", "enum": [ "improved", "declined", "unchanged", "unavailable" ] } } }, "summary": { "type": "object", "additionalProperties": { "type": "integer" } }, "changes": { "type": "array", "items": { "type": "object", "required": [ "code", "kind", "severity", "category", "title", "summary", "before", "after" ], "properties": { "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "new_risk", "improved", "activity", "status_change", "changed" ] }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "category": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "before": { "nullable": true }, "after": { "nullable": true } } } }, "generatedAt": { "type": "string", "format": "date-time" } } }, "TrustHistory": { "type": "object", "required": [ "watchlist", "currentReport", "currentDelta", "history" ], "properties": { "watchlist": { "type": "object", "required": [ "id", "profileId", "label", "input", "objectType", "visibility", "cadence", "status", "lastCheckedAt", "nextRecheckAt" ], "properties": { "id": { "type": "string", "pattern": "^wtl_[0-9a-f]{20}$" }, "profileId": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" }, "label": { "type": "string" }, "input": { "$ref": "#/components/schemas/AgentTrustReportInput" }, "objectType": { "type": "string", "enum": [ "github_repository", "ai_agent", "wallet", "arc_contract", "service_endpoint" ] }, "visibility": { "type": "string", "enum": [ "private", "public" ] }, "cadence": { "type": "string", "enum": [ "manual", "daily", "weekly" ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true }, "nextRecheckAt": { "type": "string", "format": "date-time", "nullable": true } } }, "currentReport": { "oneOf": [ { "$ref": "#/components/schemas/AgentTrustReportResponse" }, { "type": "null" } ] }, "currentDelta": { "oneOf": [ { "$ref": "#/components/schemas/TrustDeltaReport" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "type": "object", "required": [ "snapshotId", "jobId", "sequence", "score", "trustStatus", "reportHash", "verificationStatus", "proofTransactionHash", "proofUrl", "observedAt", "delta", "reportUrl" ], "properties": { "snapshotId": { "type": "string" }, "jobId": { "type": "string" }, "sequence": { "type": "integer" }, "score": { "type": "integer", "nullable": true }, "trustStatus": { "type": "string" }, "reportHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "verificationStatus": { "type": "string" }, "proofTransactionHash": { "type": "string", "nullable": true }, "proofUrl": { "type": "string", "nullable": true }, "observedAt": { "type": "string", "format": "date-time" }, "delta": { "$ref": "#/components/schemas/TrustDeltaReport" }, "reportUrl": { "type": "string" } } } } } }, "PublicTrustProfile": { "type": "object", "required": [ "profile", "currentReport", "currentDelta", "snapshots" ], "properties": { "profile": { "type": "object", "required": [ "id", "name", "objectType", "identity", "currentScore", "trustStatus", "scoreChange", "lastCheckedAt", "lastVerifiedOnArcAt", "snapshotCount" ], "properties": { "id": { "type": "string", "pattern": "^vtr_[0-9a-f]{20}$" }, "name": { "type": "string" }, "objectType": { "type": "string", "enum": [ "github_repository", "ai_agent", "wallet", "arc_contract", "service_endpoint" ] }, "identity": { "type": "object", "properties": { "agentId": { "type": "string", "nullable": true }, "repositoryUrl": { "type": "string", "nullable": true }, "wallet": { "type": "string", "nullable": true }, "contractAddress": { "type": "string", "nullable": true }, "serviceEndpoint": { "type": "string", "nullable": true } } }, "currentScore": { "type": "integer", "nullable": true }, "trustStatus": { "type": "string", "nullable": true }, "scoreChange": { "type": "integer", "nullable": true }, "lastCheckedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastVerifiedOnArcAt": { "type": "string", "format": "date-time", "nullable": true }, "snapshotCount": { "type": "integer" } } }, "currentReport": { "oneOf": [ { "$ref": "#/components/schemas/AgentTrustReportResponse" }, { "type": "null" } ] }, "currentDelta": { "oneOf": [ { "$ref": "#/components/schemas/TrustDeltaReport" }, { "type": "null" } ] }, "snapshots": { "type": "array", "items": { "type": "object", "required": [ "snapshotId", "sequence", "score", "trustStatus", "reportHash", "verificationStatus", "verifiedOnArc", "proofTransactionHash", "proofUrl", "observedAt", "newRiskCount", "resolvedRiskCount", "delta", "fullReportUrl" ], "properties": { "snapshotId": { "type": "string" }, "sequence": { "type": "integer" }, "score": { "type": "integer", "nullable": true }, "trustStatus": { "type": "string" }, "reportHash": { "type": "string" }, "verificationStatus": { "type": "string" }, "verifiedOnArc": { "type": "boolean" }, "proofTransactionHash": { "type": "string", "nullable": true }, "proofUrl": { "type": "string", "nullable": true }, "observedAt": { "type": "string", "format": "date-time" }, "newRiskCount": { "type": "integer" }, "resolvedRiskCount": { "type": "integer" }, "delta": { "$ref": "#/components/schemas/TrustDeltaReport" }, "fullReportUrl": { "type": "string" } } } } } }, "TrustRecheckQuote": { "allOf": [ { "$ref": "#/components/schemas/WorkflowQuoteResponse" }, { "type": "object", "required": [ "watchlistId", "recheckId" ], "properties": { "watchlistId": { "type": "string", "pattern": "^wtl_[0-9a-f]{20}$" }, "recheckId": { "type": "string", "pattern": "^trc_[0-9a-f]{20}$" } } } ] }, "Project360SourceType": { "type": "string", "enum": [ "github_repository", "project_wallet", "agent_id", "arc_contract", "public_api_endpoint" ] }, "Project360Module": { "type": "string", "enum": [ "github_due_diligence", "agent_trust_report", "treasury_health", "paid_api_quality", "arc_contract_analysis" ] }, "Project360DiscoveryRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "$ref": "#/components/schemas/Project360SourceType" }, "value": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "One public primary identifier. Secrets and authorization material are forbidden." } } }, "Project360Candidate": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "module", "value", "provenance", "confidence", "confidenceScore", "reason", "validationStatus", "included" ], "properties": { "id": { "type": "string", "pattern": "^src_[0-9a-f]{20}$" }, "type": { "$ref": "#/components/schemas/Project360SourceType" }, "module": { "$ref": "#/components/schemas/Project360Module" }, "value": { "type": "string" }, "provenance": { "type": "object", "required": [ "origin", "repository", "file", "lineStart", "lineEnd", "excerpt" ], "properties": { "origin": { "type": "string", "enum": [ "primary", "github_file", "public_record" ] }, "repository": { "type": "string", "nullable": true }, "file": { "type": "string", "nullable": true }, "lineStart": { "type": "integer", "minimum": 1, "nullable": true }, "lineEnd": { "type": "integer", "minimum": 1, "nullable": true }, "excerpt": { "type": "string", "nullable": true } } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 }, "reason": { "type": "string" }, "validationStatus": { "type": "string", "enum": [ "valid", "unsupported", "blocked" ] }, "included": { "type": "boolean", "enum": [ false ], "description": "Fail-closed default. The API never preselects discovered sources." } } }, "Project360Discovery": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "revision", "free", "paymentRequired", "primary", "candidatesHash", "candidates", "warnings", "errorCode", "expiresAt", "createdAt", "completedAt" ], "properties": { "id": { "type": "string", "pattern": "^dsc_[0-9a-f]{20}$" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "revision": { "type": "integer", "minimum": 1 }, "free": { "type": "boolean", "enum": [ true ] }, "paymentRequired": { "type": "boolean", "enum": [ false ] }, "primary": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "$ref": "#/components/schemas/Project360SourceType" }, "value": { "type": "string" } } }, "candidatesHash": { "type": "string", "nullable": true }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Project360Candidate" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errorCode": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "Project360DiscoveryEnvelope": { "type": "object", "additionalProperties": false, "required": [ "discovery", "created" ], "properties": { "discovery": { "$ref": "#/components/schemas/Project360Discovery" }, "created": { "type": "boolean" } } }, "Project360QuoteRequest": { "type": "object", "additionalProperties": false, "required": [ "revision", "selectedCandidateIds", "modules" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "selectedCandidateIds": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "string", "pattern": "^src_[0-9a-f]{20}$" } }, "modules": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Project360Module" } } } }, "Project360QuoteSelection": { "type": "object", "required": [ "discoveryId", "discoveryRevision", "discoverySnapshotHash", "selectionHash", "expectedCoverage", "expectedCoverageLabel", "warnings", "confirmedSources", "selectedModules", "lineItems", "pricing", "canonicalInput" ], "properties": { "discoveryId": { "type": "string", "pattern": "^dsc_[0-9a-f]{20}$" }, "discoveryRevision": { "type": "integer" }, "discoverySnapshotHash": { "type": "string" }, "selectionHash": { "type": "string" }, "expectedCoverage": { "type": "object", "required": [ "selected", "total" ], "properties": { "selected": { "type": "integer", "minimum": 1, "maximum": 5 }, "total": { "type": "integer", "enum": [ 5 ] } } }, "expectedCoverageLabel": { "type": "string", "example": "3 of 5 modules" }, "warnings": { "type": "array", "items": { "type": "string" } }, "confirmedSources": { "type": "array", "items": { "type": "object" } }, "selectedModules": { "type": "array", "items": { "$ref": "#/components/schemas/Project360Module" } }, "lineItems": { "type": "array", "items": { "type": "object", "required": [ "module", "label", "serviceSlugs", "priceUsdc", "sharedEvidence" ], "properties": { "module": { "type": "string" }, "label": { "type": "string" }, "serviceSlugs": { "type": "array", "items": { "type": "string" } }, "priceUsdc": { "type": "number", "minimum": 0 }, "sharedEvidence": { "type": "boolean" } } } }, "pricing": { "type": "object", "required": [ "moduleSubtotalUsdc", "platformFeeUsdc", "totalUsdc", "amountDueUsdc" ], "properties": { "moduleSubtotalUsdc": { "type": "number", "minimum": 0 }, "platformFeeUsdc": { "type": "number", "minimum": 0 }, "totalUsdc": { "type": "number", "minimum": 0 }, "amountDueUsdc": { "type": "number", "minimum": 0 } } }, "canonicalInput": { "type": "string" } } }, "Project360QuoteResponse": { "allOf": [ { "$ref": "#/components/schemas/WorkflowQuoteResponse" }, { "type": "object", "required": [ "project360" ], "properties": { "project360": { "$ref": "#/components/schemas/Project360QuoteSelection" } } } ] }, "Project360ReportResponse": { "type": "object", "required": [ "schema", "reportId", "workflow", "workflowType", "confirmedSources", "modules", "score", "coverage", "sections", "verification", "generatedAt" ], "properties": { "schema": { "type": "string", "enum": [ "veyra.project360.v1" ] }, "reportId": { "type": "string" }, "workflow": { "type": "string", "enum": [ "project_360" ] }, "workflowType": { "type": "string", "enum": [ "project_360" ] }, "confirmedSources": { "type": "array", "items": { "type": "object" } }, "modules": { "type": "array", "items": { "type": "object" } }, "score": { "type": "object", "required": [ "formulaVersion", "value", "confidencePercent", "confidence", "breakdown" ], "properties": { "formulaVersion": { "type": "string", "enum": [ "project360-score-v1" ] }, "value": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "confidencePercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "confidence": { "type": "string", "enum": [ "high", "medium", "low", "insufficient" ] }, "breakdown": { "type": "array", "items": { "type": "object" } } } }, "coverage": { "type": "object", "required": [ "expected", "completed", "total", "status", "label" ], "properties": { "expected": { "type": "integer", "minimum": 1, "maximum": 5 }, "completed": { "type": "integer", "minimum": 0, "maximum": 5 }, "total": { "type": "integer", "enum": [ 5 ] }, "status": { "type": "string", "enum": [ "complete", "partial", "limited", "failed" ] }, "label": { "type": "string" } } }, "sections": { "type": "array", "minItems": 15, "maxItems": 15, "items": { "type": "object" } }, "verification": { "type": "object" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "WorkflowQuoteRequest": { "type": "object", "required": [ "workflow" ], "properties": { "workflow": { "type": "string", "enum": [ "github_due_diligence", "agent_trust_report", "paid_api_quality", "sentiment_tone", "builder_update", "market_context", "custom_task" ], "example": "paid_api_quality" }, "repository": { "type": "string", "example": "circlefin/agent-commerce" }, "input": { "oneOf": [ { "$ref": "#/components/schemas/AgentTrustReportInput" }, { "$ref": "#/components/schemas/PaidApiQualityReportInput" }, { "type": "object", "additionalProperties": true, "properties": { "repository": { "type": "string", "example": "circlefin/agent-commerce" } } } ] } } }, "PaidApiQualityReportInput": { "type": "object", "description": "Input payload for Paid API Quality Report workflow. Accepts a single service ID or 1-5 service IDs to evaluate.", "properties": { "serviceId": { "type": "string", "example": "pyth-market-price" }, "serviceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "example": [ "pyth-market-price", "github-repository-intelligence" ] }, "observationWindowDays": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30, "example": 30 } } }, "AgentTrustReportInput": { "type": "object", "description": "Public identifiers for Veyra Agent Trust Report. At least one primary identifier is required.", "properties": { "agentId": { "type": "string", "pattern": "^agt_[a-z0-9]{20}$", "example": "agt_0123456789abcdefghij" }, "agentWallet": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "repositoryUrl": { "type": "string", "example": "circlefin/developer-controlled-wallets-web-sdk" }, "contractAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Optional Arc Testnet contract address" }, "serviceEndpoint": { "type": "string", "format": "uri", "description": "Optional public HTTPS endpoint; localhost and private networks are blocked" } }, "anyOf": [ { "required": [ "agentId" ] }, { "required": [ "agentWallet" ] }, { "required": [ "repositoryUrl" ] }, { "required": [ "contractAddress" ] }, { "required": [ "serviceEndpoint" ] } ] }, "WorkflowQuoteResponse": { "type": "object", "required": [ "quoteId", "workflow", "totalUsdc", "sponsored", "expiresAt", "requiredPayment" ], "properties": { "quoteId": { "type": "string", "example": "qte_9f81a2b3c4d5" }, "workflow": { "type": "string", "example": "github_due_diligence" }, "repository": { "type": "object", "nullable": true, "properties": { "fullName": { "type": "string", "example": "circlefin/agent-commerce" }, "canonicalUrl": { "type": "string", "example": "https://github.com/circlefin/agent-commerce" } } }, "totalUsdc": { "type": "number", "example": 0.002 }, "sponsored": { "type": "boolean", "example": true }, "checkout": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sponsored", "arc_transaction" ], "example": "sponsored" }, "asset": { "type": "string", "example": "USDC" }, "network": { "type": "string", "example": "arc-testnet" } } }, "downstreamSettlement": { "type": "string", "example": "server_side_x402" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-07-24T22:15:00.000Z" }, "requiredPayment": { "type": "object", "properties": { "network": { "type": "string", "example": "arc-testnet" }, "asset": { "type": "string", "example": "USDC" }, "amount": { "type": "number", "example": 0 }, "treasuryAddress": { "type": "string", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "chainId": { "type": "number", "example": 5042002 } } } } }, "RunLaunchRequest": { "type": "object", "required": [ "quoteId" ], "properties": { "quoteId": { "type": "string", "example": "qte_9f81a2b3c4d5" }, "paymentAuthorization": { "type": "object", "properties": { "type": { "type": "string", "example": "arc_transaction" }, "payload": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" } } } } }, "RunLaunchResponse": { "type": "object", "required": [ "runId", "status", "pollAfterMs" ], "properties": { "runId": { "type": "string", "example": "job_01h9a8b7c6d5" }, "status": { "type": "string", "example": "queued" }, "pollAfterMs": { "type": "number", "example": 2000 } } }, "RunStatusResponse": { "type": "object", "required": [ "runId", "status", "progress", "stage", "pollAfterMs" ], "properties": { "runId": { "type": "string", "example": "job_01h9a8b7c6d5" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "completed_with_warnings", "failed", "expired" ], "example": "completed" }, "progress": { "type": "number", "example": 1 }, "stage": { "type": "string", "example": "completed" }, "pollAfterMs": { "type": "number", "example": 0 }, "reportId": { "type": "string", "example": "job_01h9a8b7c6d5" }, "verification": { "type": "object", "properties": { "status": { "type": "string", "example": "verified" }, "verifiedSteps": { "type": "number", "example": 2 }, "requiredSteps": { "type": "number", "example": 2 } } } } }, "StructuredReportResponse": { "type": "object", "required": [ "reportId", "workflow", "repository", "status", "executiveSummary", "projectPurpose", "technology", "activity", "strengths", "risks", "questionsBeforeAdoption", "confidence", "verification", "generatedAt" ], "properties": { "reportId": { "type": "string", "example": "job_01h9a8b7c6d5" }, "workflow": { "type": "string", "example": "github_due_diligence" }, "repository": { "type": "object", "nullable": true, "properties": { "fullName": { "type": "string", "example": "circlefin/agent-commerce" }, "canonicalUrl": { "type": "string", "example": "https://github.com/circlefin/agent-commerce" } } }, "status": { "type": "string", "example": "completed" }, "verdict": { "type": "object", "nullable": true, "required": [ "code", "label", "confidence", "summary", "reasons", "blockingFindings", "evidenceCoverage" ], "properties": { "code": { "type": "string", "enum": [ "proceed_with_standard_review", "proceed_with_conditions", "pause_for_review", "insufficient_evidence" ] }, "label": { "type": "string", "example": "Proceed with standard review" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "summary": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "blockingFindings": { "type": "array", "items": { "type": "string" } }, "evidenceCoverage": { "type": "object", "properties": { "assessedCategories": { "type": "number" }, "highConfidenceCategories": { "type": "number" }, "totalCategories": { "type": "number" }, "ratio": { "type": "number" } } } } }, "executiveSummary": { "type": "string", "example": "Repository due diligence completed with strong governance and regular commit activity." }, "projectPurpose": { "type": "object", "properties": { "summary": { "type": "string" }, "primaryInterface": { "type": "string" }, "developmentStage": { "type": "string" }, "targetUsers": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } } }, "technology": { "type": "object", "properties": { "primaryLanguage": { "type": "string", "example": "TypeScript" }, "frameworks": { "type": "array", "items": { "type": "string" }, "example": [ "Next.js", "React" ] }, "hasWorkflows": { "type": "boolean", "example": true }, "workflowCount": { "type": "number", "example": 3 } } }, "activity": { "type": "object", "properties": { "commitCount30d": { "type": "number", "example": 42 }, "commitCount90d": { "type": "number", "example": 120 }, "commitCount180d": { "type": "number", "example": 250 }, "lastCommitAt": { "type": "string", "example": "2026-07-24T18:00:00Z" } } }, "strengths": { "type": "array", "items": { "type": "string" }, "example": [ "Comprehensive test suite", "Active maintainers" ] }, "risks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "low_test_coverage" }, "title": { "type": "string", "example": "Moderate Test Coverage" }, "severity": { "type": "string", "example": "low" }, "description": { "type": "string", "example": "Some helper functions lack unit tests." }, "impact": { "type": "string", "example": "Potential edge case bugs in error handlers." } } } }, "questionsBeforeAdoption": { "type": "array", "items": { "type": "string" }, "example": [ "What is the long-term maintenance roadmap?" ] }, "confidence": { "type": "string", "example": "high" }, "verification": { "type": "object", "properties": { "status": { "type": "string", "example": "verified" }, "network": { "type": "string", "example": "arc-testnet" }, "proofs": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string", "example": "rcpt_01h9a8b7" }, "txHash": { "type": "string", "nullable": true, "example": "0xabcd1234ef567890" }, "status": { "type": "string", "example": "verified" }, "explorerUrl": { "type": "string", "example": "https://testnet.arcscan.app/tx/0xabcd1234ef567890" } } } } } }, "generatedAt": { "type": "string", "format": "date-time", "example": "2026-07-24T21:05:00.000Z" } } }, "AgentTrustReportResponse": { "type": "object", "required": [ "kind", "version", "workflowType", "reportId", "input", "subject", "trustScore", "executiveSummary", "identity", "codeIntelligence", "executionReliability", "paymentsAndReceipts", "services", "contractTransparency", "endpointAvailability", "evidenceBackedStrengths", "risksAndReviewItems", "questionsBeforeIntegration", "dataFreshness", "unavailableSources", "limitations", "verification", "generatedAt" ], "properties": { "kind": { "type": "string", "enum": [ "agent_trust_report" ] }, "version": { "type": "integer", "enum": [ 1 ] }, "workflowType": { "type": "string", "enum": [ "agent_trust_report" ] }, "reportId": { "type": "string" }, "input": { "$ref": "#/components/schemas/AgentTrustReportInput" }, "subject": { "type": "object", "properties": { "name": { "type": "string" }, "agentId": { "type": "string", "nullable": true }, "wallet": { "type": "string", "nullable": true }, "repository": { "type": "object", "nullable": true, "properties": { "fullName": { "type": "string" }, "canonicalUrl": { "type": "string" } } } } }, "trustScore": { "type": "object", "required": [ "overall", "status", "categories", "excludedCategories" ], "properties": { "overall": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Deterministic confidence-weighted score; null when fewer than two categories are scorable" }, "status": { "type": "string", "enum": [ "strong_signals", "review_recommended", "high_attention", "limited_data" ] }, "categories": { "type": "object", "additionalProperties": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "evidenceCount": { "type": "integer" }, "summary": { "type": "string" }, "positiveSignals": { "type": "array", "items": { "type": "object" } }, "reviewItems": { "type": "array", "items": { "type": "object" } } } } }, "excludedCategories": { "type": "array", "items": { "type": "string" } } } }, "executiveSummary": { "type": "array", "items": { "type": "string" } }, "identity": { "type": "object" }, "codeIntelligence": { "type": "object" }, "executionReliability": { "type": "object" }, "paymentsAndReceipts": { "type": "object" }, "services": { "type": "object" }, "contractTransparency": { "type": "object" }, "endpointAvailability": { "type": "object" }, "evidenceBackedStrengths": { "type": "array", "items": { "type": "object" } }, "risksAndReviewItems": { "type": "array", "items": { "type": "object" } }, "questionsBeforeIntegration": { "type": "array", "items": { "type": "string" } }, "dataFreshness": { "type": "array", "items": { "type": "object" } }, "unavailableSources": { "type": "array", "items": { "type": "string" } }, "limitations": { "type": "array", "items": { "type": "string" } }, "verification": { "type": "object", "required": [ "status", "verifiedOnArc", "network", "chainId", "reportHash", "proofs" ], "properties": { "status": { "type": "string", "enum": [ "verified", "verification_pending", "verification_failed" ] }, "verifiedOnArc": { "type": "boolean", "description": "True only when a verified Arc proof response hash exactly matches reportHash" }, "network": { "type": "string", "enum": [ "arc-testnet" ] }, "chainId": { "type": "integer", "enum": [ 5042002 ] }, "reportHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$", "description": "Deterministic SHA-256 hash of the canonical report evidence and score snapshot" }, "proofs": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ] }, "transactionHash": { "type": "string", "nullable": true }, "explorerUrl": { "type": "string", "nullable": true } } } } } }, "generatedAt": { "type": "string", "format": "date-time" } } } }, "responses": { "BadRequest": { "description": "Invalid input or repository reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "Unauthorized": { "description": "Missing or invalid Bearer token credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "PaymentRequired": { "description": "Payment authorization required for paid workflow quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "Forbidden": { "description": "Credential scope denied or workflow disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "NotFound": { "description": "Quote, run, or report not found or unowned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "Conflict": { "description": "Idempotency conflict, mutation already in progress, or quote already executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "RateLimited": { "description": "Spending limit or rate policy exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } }, "ServiceUnavailable": { "description": "Downstream x402 service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineError" } } } } } } }